Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarifications in the target tier policy #90498

Merged
merged 5 commits into from
Jan 18, 2022

Conversation

joshtriplett
Copy link
Member

We've added several targets since the introduction of the target tier policy. Based on experiences of those adding such targets, and discussions around such additions, clarify the target tier policy to make it easier to follow and work with.

None of these changes substantively change the requirements on targets. (In some cases the changes do direct target submitters to follow specific process requirements for the addition of a target, such as how to respond to requirements, where to put target-specific documentation, or what should appear in that documentation. Those changes are procedural in nature and document the procedures we already direct people to follow.)

  • Clarify how to quote and respond to the target tier policy requirements. Several times, people have seemed unclear on how to respond to some of the policy requirements, particularly those that just state things the target developers must not do (e.g. not posting to PRs that break the target). Add a note that such requirements just need acknowledgement, nothing more.
  • Clarify dependency requirements in the face of cross-compilation. I previously phrased this confusingly in terms of "host tools", since that is the case where an exception applies (allowing proprietary target libraries commonly used by binaries for the target). Rephrase it to apply equally to cross-compilation. This doesn't change the net effect of the requirements, since other requirements already cover the dependencies of the Rust toolchain.
  • Clarify documentation about running binaries. The requirement for target documentation talks about "running tests", but tier 3 targets often don't support running the full testsuite, and in practice the documentation for how to run an individual binary may be more useful. Change "running tests" to "running binaries, or running tests".
  • Explain where to place target-specific documentation (a subdirectory of platform-support, with a link from the platform-support entry for the target).
  • Add a template for target-specific documentation.

Several times, people have seemed unclear on how to respond to some of
the policy requirements, particularly those that just state things the
target developers must *not* do (e.g. not posting to PRs that break the
target). Add a note that such requirements just need acknowledgement,
nothing more.

Make quoting and responding a "must" rather than an "is encouraged to",
since it's easier to review the requirements that way.
The requirement on dependencies was phrased in terms of "host tools",
but it was also intended to apply equally to targets that only support
cross-compilation. Only the exception (for libraries commonly needed for
binaries on the target) was intended to apply to host tools. Reword the
requirement to talk about the dependencies required for "compiling,
linking,and emitting functional binaries, libraries, or other code for
the target", rather than generically in terms of dependencies for
rustc/cargo.

This doesn't change the net effect of the requirements, since other
requirements already stated that the target can't make the Rust
toolchain depend on proprietary libraries. However, this should make the
requirements clearer.
The requirement for target documentation talks about "running tests",
but tier 3 targets often don't support running the full testsuite, and
in practice the documentation for how to run an individual binary may be
more useful. Change "running tests" to "running binaries, or running
tests".
Explain that target-specific documentation should appear in a
subdirectory of platform-support, with a link from the target's entry on
the platform-support page.
@joshtriplett joshtriplett added T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. T-release Relevant to the release subteam, which will review and decide on the PR/issue. labels Nov 2, 2021
@rust-highfive
Copy link
Collaborator

r? @steveklabnik

(rust-highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 2, 2021
@joshtriplett
Copy link
Member Author

r? @pietroalbini

I don't think this needs a full three-team FCP like the original policy. It's documenting process that we're already following for the addition of targets, and clarifying corner cases and unclear points without substantively changing the requirements for targets.

All of this grew out of discussions around the additions of targets thus far, including unclear processes (where does documentation go), and corner cases (what about cross-compilation).

@JohnCSimon JohnCSimon added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Dec 5, 2021
@pietroalbini
Copy link
Member

Can someone else review this? Won't have time myself.

@Mark-Simulacrum
Copy link
Member

I agree the changes in this PR do not imply/suggest any significant change or need full three-team FCP. I'm going to go ahead and r+, but also intend to announce this PR in a T-compiler meeting to bring attention to the new template in particular.

(I imagine there may be edits and/or suggestions to the text, but it seems clear that the text can be iterated on in the future).

@bors r+ rollup

@bors
Copy link
Contributor

bors commented Jan 17, 2022

📌 Commit f863e4c has been approved by Mark-Simulacrum

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 17, 2022
bors added a commit to rust-lang-ci/rust that referenced this pull request Jan 17, 2022
…askrgr

Rollup of 10 pull requests

Successful merges:

 - rust-lang#90498 (Clarifications in the target tier policy)
 - rust-lang#92164 (Implement `#[rustc_must_implement_one_of]` attribute)
 - rust-lang#92729 (rustc_codegen_llvm: Remove (almost) unused span parameter from many functions in metadata.rs)
 - rust-lang#92752 (Correct minor typos in some long error code explanations)
 - rust-lang#92801 (Enable wrapping words by default)
 - rust-lang#92825 (Rename environment variable for overriding rustc version)
 - rust-lang#92877 (Remove LLVMRustMarkAllFunctionsNounwind)
 - rust-lang#92936 (rustdoc: Remove `collect` in `html::markdown::parse`)
 - rust-lang#92956 (Add `log2` and `log10` to `NonZeroU*`)
 - rust-lang#92960 (Use `carrying_{mul|add}` in `num::bignum`)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 67bcbde into rust-lang:master Jan 18, 2022
@rustbot rustbot added this to the 1.60.0 milestone Jan 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. T-release Relevant to the release subteam, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants